Skip to content

feat: build the OpenStack section from the C5C3/cobaltcore docs - #90

Draft
berendt wants to merge 4 commits into
cobaltcore-dev:mainfrom
berendt:implement/issue-89-cobaltcore-overlay
Draft

berendt wants to merge 4 commits into
cobaltcore-dev:mainfrom
berendt:implement/issue-89-cobaltcore-overlay

Conversation

@berendt

@berendt berendt commented Nov 9, 2026 •

Copy link
Copy Markdown

Closes #89. The cobaltcore-dev/docs side of C5C3/cobaltcore#1646; the C5C3/cobaltcore side shipped in C5C3/cobaltcore#1647.

The OpenStack section is now the documentation of C5C3/cobaltcore, checked out at build time and mounted under /openstack/. No file of C5C3/cobaltcore is committed here. The hand-written OpenStack pages, which described a Helm chart that does not exist and covered five of nine services, are gone; the overlay serves their URLs.

Commits

  1. feat: build the OpenStack section from the C5C3/cobaltcore docs. hack/sync-cobaltcore.sh puts a sparse checkout (docs, tests, deploy) into docs/_upstream/cobaltcore, ignored by git and docker. npm runs it before docs:dev and docs:build; it leaves an existing checkout alone, and with COBALTCORE_SRC it copies a local checkout. docs/.vitepress/overlay.ts (the prototype from Build the OpenStack section from the C5C3/cobaltcore docs as a build-time overlay #89) mounts the pages that publish.json lists: rewrites maps them, srcExclude drops every other Markdown file of the checkout, and a markdown-it rule resolves links against the real source file. Links to published pages stay here, links to unpublished pages go to c5c3.github.io/cobaltcore, and links to files outside docs/ go to GitHub. The /openstack/ sidebar is the upstream sidebar pruned to published pages, and "Edit this page" opens the file in C5C3/cobaltcore.
  2. ci: build with the C5C3/cobaltcore docs and rebuild nightly. static.yml checks out C5C3/cobaltcore main sparsely before npm ci (no persisted token), and a nightly schedule rebuilds and deploys the site.
  3. build: require Node 22.18 and install bash and git in the image. Loading the upstream sidebar.ts needs Node's built-in type stripping. The image needs bash and git for the sync hook. The README describes the OpenStack section and the local preview.
  4. docs: align the pages that describe the OpenStack layer. Step 5 of the minimal environment and the platform bootstrap order no longer describe a Helm install. The diagrams and the full-deployment checklist list all nine services, Getting Started gains an OpenStack control plane track, and docs/networking/ovn.md links /openstack/ovn.

The optional table CSS from #89 is left out: VitePress' default theme already gives .vp-doc table display: block and overflow-x: auto.

Verification

Against C5C3/cobaltcore@840f88fd8:

  • npm run docs:sync && npm run docs:build with Node 22.23 and 24.21: 81 pages under /openstack/, no dead link, nothing else of the checkout rendered. Rebased onto main and built with Node 25.1: 124 pages, 81 of them under /openstack/; the 43 pages outside /openstack/ are the same as on main, and the six old OpenStack URLs are served by the overlay.
  • The 81 pages hold 371 internal links (all targets exist), 512 links to c5c3.github.io (83 distinct URLs, all HTTP 200) and 81 edit links to C5C3/cobaltcore/edit/main/docs/…. The sidebar groups are Quick Starts, Architecture, Guides, Services, Reference.
  • vitepress preview: /openstack/, a guide, /openstack/nova and /openstack/quick-start-controlplane answer 200. In vitepress dev, the page module of a guide carries the rewritten links.
  • hack/sync-cobaltcore.sh: clones when the checkout is missing, leaves it alone on the next run, copies with COBALTCORE_SRC, and stops with a message on an incomplete directory or a wrong COBALTCORE_SRC. shellcheck reports nothing.
  • docker compose build, then docker compose run vitepress npm run docs:build with the checkout missing: the hook clones in the container, and the build produces 81 OpenStack pages.
  • The docs-overlay job of C5C3/cobaltcore, emulated against this branch: its check finds docs/.vitepress/overlay.ts, and npm ci && npm run docs:build with the job's checkout passes and leaves the checkout alone.
  • actionlint reports nothing for static.yml.

After the merge, the nightly build and the docs-overlay job of C5C3/cobaltcore run against main here; C5C3/cobaltcore#1646 can be closed once cobaltcore.dev shows the section.

🤖 Generated with Claude Code

@berendt

berendt commented Nov 9, 2026

Copy link
Copy Markdown
Author

First try integrating the docs from the c5c3/cobaltcore repository AS-IS as a first step.

@artemkovalyov

Copy link
Copy Markdown
Member

@berendt, why not migrating your workflows to this repo and setting up an infra for that? Are there any engineering or organizational blockers?

@berendt

berendt commented Nov 10, 2026

Copy link
Copy Markdown
Author

@berendt, why not migrating your workflows to this repo and setting up an infra for that? Are there any engineering or organizational blockers?

I'm not quite sure yet how that's supposed to work. In my opinion, documentation belongs with the individual projects and shouldn't be managed in a central Docs repository. For example, we have E2E tests for every guide we have. How is that supposed to work properly if the guide is in a different repository than our E2E tests? I think it's a good idea to publish the documentation in a curated, centralized location. In my opinion, the documentation should be maintained in the respective repositories. Otherwise, it will quickly become disjointed. Even if we later publish security advisories or release interim versions for individual projects along with release notes, I believe that this information belongs within the respective projects and should only be published centrally afterward.

The OpenStack section was a set of hand-written pages that described a
Helm chart that does not exist and covered five of the nine services.
C5C3/cobaltcore documents the OpenStack layer completely and declares in
docs/.vitepress/publish.json which of its pages cobaltcore.dev may
publish (C5C3/cobaltcore#1647).

hack/sync-cobaltcore.sh puts a sparse checkout of C5C3/cobaltcore (docs,
tests, deploy) into docs/_upstream/cobaltcore. npm runs it before
docs:dev and docs:build; it leaves an existing checkout alone and copies
a local checkout when COBALTCORE_SRC names one. The directory is
ignored by git and docker.

docs/.vitepress/overlay.ts mounts the published pages under /openstack/
without copying a file: rewrites maps the checkout, srcExclude drops
every other Markdown file of it, and a markdown-it rule resolves each
link against the page's real source file. A link to a published page
stays on this site, a link to an unpublished page goes to
c5c3.github.io/cobaltcore, and a link to a file outside docs/ goes to
GitHub. The /openstack/ sidebar is the upstream sidebar pruned to the
published pages, and "Edit this page" opens the file in
C5C3/cobaltcore. The overview pages of the nine service operators keep
the URLs of the old pages, /openstack/nova and so on, so the old pages
go.

Built against C5C3/cobaltcore@840f88fd8 with Node 22.23: 123 pages, 81
of them under /openstack/, no dead link; the 371 internal links of
those pages resolve and their 83 distinct links to c5c3.github.io
answer 200.

Part of C5C3/cobaltcore#1646.

On-behalf-of: @SAP
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
The build job checks out C5C3/cobaltcore main into
docs/_upstream/cobaltcore before npm ci, sparsely (docs, tests, deploy)
and without persisting the token, so the sync hook of docs:build finds
the checkout and leaves it alone. A nightly schedule rebuilds and
deploys the site, so a change to the C5C3/cobaltcore docs reaches the
OpenStack section within a day; the deploy job already runs on every
event but a pull request. actionlint reports nothing for the workflow.

Part of C5C3/cobaltcore#1646.

On-behalf-of: @SAP
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
The overlay loads docs/.vitepress/sidebar.ts of C5C3/cobaltcore with
import(), which needs the type stripping Node 22.18 and later has built
in; the README said Node 18. CI and the image already run Node 26.

The image runs docs:dev, whose predocs:dev hook runs
hack/sync-cobaltcore.sh. node:26-alpine has neither bash nor git, so the
image installs both and copies the script. With docs/_upstream absent,
`docker compose run vitepress npm run docs:build` cloned C5C3/cobaltcore
into the mounted directory and built 81 pages under /openstack/.

The README describes the OpenStack section, the sync step and the
preview of a local C5C3/cobaltcore checkout with COBALTCORE_SRC.

Part of C5C3/cobaltcore#1646.

On-behalf-of: @SAP
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
Five pages described OpenStack the way the removed pages did. Step 5 of
the minimal environment installed a Helm chart cobaltcore/openstack
that does not exist; it now explains the ControlPlane resource and
points to Quick Start (ControlPlane) and Quick Start (metal-stack). The
platform bootstrap order said "via Helm" and now names the operators
and the ControlPlane resource.

The diagrams of the architecture overview and the full deployment list
the nine services the OpenStack section covers, and the OpenStack
checklist of the full deployment links Quick Start (ControlPlane) and
adds Placement, Barbican and Horizon. Getting Started gains an
OpenStack control plane track, and docs/networking/ovn.md links the OVN
operator at /openstack/ovn.

Part of C5C3/cobaltcore#1646.

On-behalf-of: @SAP
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Christian Berendt <berendt@23technologies.cloud>
@berendt
berendt force-pushed the implement/issue-89-cobaltcore-overlay branch from 93b324b to 9e36ca4 Compare November 10, 2026 19:37
@artemkovalyov

Copy link
Copy Markdown
Member

@berendt, why not migrating your workflows to this repo and setting up an infra for that? Are there any engineering or organizational blockers?

I'm not quite sure yet how that's supposed to work. In my opinion, documentation belongs with the individual projects and shouldn't be managed in a central Docs repository. For example, we have E2E tests for every guide we have. How is that supposed to work properly if the guide is in a different repository than our E2E tests? I think it's a good idea to publish the documentation in a curated, centralized location. In my opinion, the documentation should be maintained in the respective repositories. Otherwise, it will quickly become disjointed. Even if we later publish security advisories or release interim versions for individual projects along with release notes, I believe that this information belongs within the respective projects and should only be published centrally afterward.

We need to talk and find a meaningful solution. I'll also need to onboard you to the latest state.

@artemkovalyov

Copy link
Copy Markdown
Member

As agreed, let's follow with the repo in the Org and move the code & docs there.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Build the OpenStack section from the C5C3/cobaltcore docs as a build-time overlay

2 participants